TPUG - Toronto PET Users Group/TPUG Users Group CD/TPUG Users Group CD.iso/AMIGA/(A)TC/(A)TCA.ADF/hlplusdemo/Documentation/userman.doc

Text File | 1992-07-04 | 39KB | 1,041 lines

HAMLAB PLUS 2.0.6
USER'S MANUAL

(c) Copyright 1990-1992 J. E. Hanway
All rights reserved.

IN THIS DOCUMENT:

SETUP
        SYSTEM REQUIREMENTS
        INSTALLATION
        CONFIGURATION
        ADDING NEW FILTERS AND EXPORTERS

QUICK START

USER INTERFACE REFERENCE
        COMMAND LINE OPTIONS
        ENVIRONMENT VARIABLE
        WORKBENCH TOOLTYPES
        THE MAIN WINDOW
        THE ABOUT WINDOW
        THE CONFIGURATION WINDOW
        THE COLOR CONTROL WINDOW
        THE OUTPUT MODE WINDOW
        THE AREXX CONSOLE
        AREXX FUNCTION KEYS

THE HAMLAB PLUS PIPELINE AND CACHES


SETUP

SYSTEM REQUIREMENTS

HAMLAB PLUS runs on any Amiga, under either release 1.3 or 2.0 of the
Amiga operating system.  At least 1 meg of RAM is required.

For full functionality, HAMLAB PLUS requires EITHER

        AmigaOS Release 2
OR
        AmigaOS 1.3 and the ARP library.

If you have neither the ARP library nor Release 2, you can still run
HAMLAB PLUS, with two limitations:

        It will only have a poor excuse for a file requester.

        HAMLAB 1.x input filters cannot be used.

In any case, only the ARP library itself (LIBS:arp.library) is
used.  The ARP commands in C: do not need to be installed.  ARP
is not required for operation under AmigaOS Release 2.

In order to use HAMLAB 1.x input filters, HAMLAB PLUS requires the
AmigaDOS PIPE: device.  Different versions of PIPE: are supplied with
1.3 and 2.0.  If you encounter problems, check your DEVS:mountlist
file to make sure that the correct version is used.  The 1.3 PIPE:
entry should reference "l:pipe-handler" while the 2.0 entry should
reference "l:queue-handler"

INSTALLATION

Installing a working copy of HAMLAB PLUS on your disk:

1. Decide where you'd like to install HAMLAB PLUS, creating
   a new drawer if necessary.

2. Copy the following from the original HAMLAB PLUS disk to the drawer
   that you chose in the last step. (Just drag icons in the Workbench,
   or use the CLI.)

        The "HamLabPlus" program.

        The "HamLab.config" file. (*)

        The "Filters" drawer.   (This contains filters and exporters.)

        The "Curves" drawer.    (This contains color response curves.)

        (*) If you intend to run HAMLAB PLUS only from the Workbench,
        just place the HamLab.config icon in the same drawer as the
        program.  Otherwise, move it to either the S: or the DEVS:
        directory.

3. (optional) Copy the following, if you wish:

        The "Documentation" drawer.

        The "Rexx" drawer. (This contains example AREXX scripts.
        To use them, they must be copied to the directory where
        REXX: is assigned.)

4. Run the HAMLAB PLUS copy you just made.  A "HamLab Config Problem"
   requester may be displayed.  If so, just click the "Ok" button
   until the main window appears.

5. Click the "Configuration..." button to open the Config window.

6. In the "Filter Path" line, enter the full path name of the
   filters drawer.

7. Drag the Config window to the upper left corner of the screen.
   This will prevent it from opening every time you run the program.

8. Click the "Save All" button.  This will display a file requester
   with the name of your default config file filled in.  Confirm the
   save.

9. Close the main window to exit the program.

10.Run HAMLAB PLUS again.  This time the "Config Problem" requester
   should not appear.  If it does, double check the "Filter Path"
   entry and make sure that the config file is being saved in the
   correct directory.

Installing other files:

ARP library

The ARP library is not used if you are running AmigaOS Release 2.

If you are running AmigaOS 1.3 and don't have ARP, copy
arp.library from the libs directory of the HAMLAB PLUS disk to
the LIBS: directory of your boot disk.  If you obtained HAMLAB
PLUS as a demo version from a source of freely distributable
software, look there for ARP version 1.3.

PIPE: device

The PIPE: device is supplied as a standard part of both 1.3 and 2.0.
So unless you've explicitly taken it out of your system, you already
have it.  If you need to replace it, you'll have to go back to
your original AmigaDOS disks to get the correct entry for
DEVS:mountlist, plus the proper handler file for the L: directory.
For 1.3, the handler is named "pipe-handler" and for 2.0 it is named
"queue-handler".

Finally, somewhere in your s:startup-sequence or user-startup, you
should have a "mount PIPE:" command.


CONFIGURATION

When HAMLAB PLUS is run, it loads its configuration information from
a "config file."  The config file is named "HamLab.config" and
HAMLAB PLUS will look for it in the following places, in order:

        the current directory
        S:
        DEVS:

The config file contains the following types of information:

        Directory names where HAMLAB PLUS creates or looks for files
        (filter programs and temporary files, for example)

        Information about filter and exporter programs that are
        installed.

        Positions for all HAMLAB PLUS windows, and/or whether they
        should open when the program is started.

        How much memory and/or disk space HAMLAB PLUS can use.

        Initial selections for all settings (resolution, size,
        dithering, etc.).

When first installing HAMLAB PLUS, the most important things to get
configured correctly are the filters.  Without them, HAMLAB PLUS
is unable to read any images.  Once you have followed the installation
instructions, the config file will be updated so that filters will be
found in the correct directory and will be known to HAMLAB PLUS.
Later, you'll probably want to tailor its memory and disk usage to
your system.  See the section on caches for more information.

The config file is a text file that can be customized with a text
editor, but editing it by hand isn't required.  The easiest way to
create or update a config file is to run HAMLAB PLUS, set everything
up the way you like it, and select either "Save" or "Save All" in the
configuration window.

"Save" saves only settings that correspond to different types of
images (resolution, dithering, etc.). For example, you may have one
group of settings for hi-res images,  and another for low-res ones.
"Save All" saves all settings (except cropping, which is always reset
for each picture) and is suitable for creating or updating your master
HamLab.config file.

Of course, you can create config files by hand that have any number of
settings in them.  See the separate document "cmd-ref.doc" for more
details on the config file format.

ADDING NEW FILTERS AND EXPORTERS

From time to time new filters and exports may be released for HAMLAB
PLUS.  In order to use a new filter, you must first update the
HamLab.config file so that HAMLAB PLUS knows about it.  Perform the
following steps to do so:

1. Copy the new filter to the HamLab filters directory. (If you
   followed the standard installation, the filters directory should
   be a drawer named "Filters")

2. Run HAMLAB PLUS and bring up the Configuration window.

3. Select "Scan Filters."  This will test every program in the
   filters directory to see if it is a filter or exporter and, if
   it is, what its characteristics are.

4. When the scanning process completes, move the config window to
   the upper left corner of the screen (to prevent its position
   from being saved) and select "Save All."

QUICK START

HAMLAB PLUS can be started from the CLI or by double-clicking its
Workbench icon.  The six large buttons at the bottom of the main
window control the major functions of HAMLAB PLUS.

OPEN an image to begin working on it.  This will attempt to identify
it, and read enough of it to determine its size.  Once opened, you can
adjust HAMLAB PLUS's settings and execute one or more of the three
main functions as follows.

EXPORT reads the image, converts it to 24 bits, crops, scales, and
color corrects it, then saves it in a 24-bit format.  Hitting the
EXPORT button displays a list of formats that can be exported.

DISPLAY reads the image, converts it to 24 bits, crops, scales, color
corrects it, then reduces it to a displayable format and displays the
image on the screen.  The displayable format can be controlled by
bringing up the Output Mode window with the "Change Output Mode..."
button and changing the settings before hitting DISPLAY or SAVE.

SAVE reads the image, converts it to 24 bits, crops, scales, color
corrects it, then reduces it to a displayable format and saves it as
an IFF file.

The remaining main buttons do the following:

REVERT resets all settings to what they were for the last EXPORT,
DISPLAY, or SAVE operation you attempted.

CLEAR unloads the current image and frees any temporary memory or
disk space associated with it.

Other windows:

The Output window lets you change the mode used to display and save
images.

The Color Control window lets you adjust "color response curves" used
by HAMLAB PLUS for color correction.  You can modify the curves by
drawing them by hand, or use the controls for brightness, contrast,
and gamma.

The Configuration window lets you change some basic features of how
HAMLAB PLUS operates, such as how much and what kind of storage is
used for temporary data.

USER INTERFACE REFERENCE

COMMAND LINE OPTIONS

HamLab Plus understands the following command line options: (You don't
have to enter them in upper case.)

        PORTNAME <name>

        Sets the base name for HAMLAB PLUS's AREXX port.  The default
        is HAMLAB, and HAMLAB PLUS will add a suffix to that so that
        the first copy of HAMLAB PLUS running will have a port named
        HAMLAB.1, the second will be HAMLAB.2, and so on.  This name
        is also used for HAMLAB PLUS's public screen, if you tell it
        to make one (see below).

        SETTINGS <filename>

        Specifies the filename of a HAMLAB PLUS config file to be read
        in after the default config file.  Note that this is read
        in addition to--not instead of--the default config file.

        STARTUP <filename>

        Specifies the filename of an AREXX script to be run whenever
        HAMLAB PLUS starts up.

        PUBSCREEN <screenname>

        (AmigaOS Release 2 only)
        Specifies the name of a public screen where HAMLAB PLUS will
        open its windows.  The public screen must already be open.
        By default HAMLAB PLUS uses the Workbench screen.

        SCREEN  <screentype>

        Forces HAMLAB PLUS to open a new screen for its windows.
        <screentype> is made up of one or more keywords, separated
        by slashes, and without any spaces between them.  The valid
        keywords are:

        LACE    forces the screen to be interlaced

        NOLACE  forces the screen not to be interlaced

        PUBLIC  makes the screen public (AmigaOS Release 2 only)
                The name specified by PORTNAME will be used as
                the public screen name. (Or HAMLAB will be used
                if you don't specify a name.)

        COLORS  allows you to specify the four colors to be used
                on the HAMLAB PLUS screen.  The colors are specified
                as three hex digits (0-f) each (r, g, b), and each
                color is separated by a slash.

                If you are running AmigaOS 1.3, and you tell HAMLAB
                PLUS to open a new screen without specifying the
                colors to use, HAMLAB PLUS will use colors close to
                the default 2.0 colors.  If you are running AmigaOS
                Release 2 and don't specify the colors, HAMLAB PLUS
                will copy them from the Workbench screen.

        HAMLAB PLUS doesn't allow a lot of screen options.  The size
        will always be cloned from the Workbench screen (adjusted by
        LACE or NOLACE), and the depth will always be 2 bit planes
        (4 colors).

        If neither LACE nor NOLACE are specified, the screen will
        use the current Workbench screen's interlace setting.

        Example:        SCREEN LACE/PUBLIC/COLORS/000/fff/aaa/69b

        CONVERT <pattern ...>

        This option causes HAMLAB PLUS to be run in "simple batch
        mode."

        In this mode, HAMLAB PLUS will attempt to load and save each
        file that matches the AmigaDOS wild card pattern(s) you enter.
        When all files are processed, HAMLAB PLUS will exit.

        You will not be able to change any HAMLAB PLUS settings during
        the batch operation.  The only way to control them is to
        load them from a config file before the batch starts. (This is
        where the SETTINGS option is useful.)

        Each converted file will be saved in the output directory
        specified in your configuration file.

        CONVERT must always be the last option on the command line.
        The rest of the command line is treated as filename patterns
        for the CONVERT process.

Command line examples:

        1> HamLabPlus PORTNAME HLPLUS SCREEN LACE
        1> HamLabPlus SETTINGS hires.config CONVERT incoming:#?.gif

ENVIRONMENT VARIABLE (AmigaOS 2.x ONLY)

Under AmigaOS 2.x, you can use the SetEnv CLI command to put common
HAMLAB PLUS command line options into the HAMLABARGS variable.  For
example:

        1> SetEnv HAMLABARGS PUBSCREEN MyPublicScreen
        1> HamLabPlus
        [hl+ opens on MyPublicScreen]

WORKBENCH TOOLTYPES

You can also enter HAMLAB PLUS command line options as tool types in
HAMLAB PLUS's icon.  You should note the following:

        Tool type keywords should be in upper case.

        Only one keyword can be entered per line.

        The keyword must be followed by an equals sign and a value.
        (For keywords that take no value, just enter a space.)

Examples:

        PORTNAME=HLPLUS
        SCREEN=LACE/PUBLIC/COLORS/000/fff/aaa/69b

THE MAIN WINDOW

The main window is always visible when HAMLAB PLUS is running.

There are two text display areas across the top of the main window,
labeled "Input" and "Output."  These display the name, size, and
format of the input and output images, respectively.

Between the two text areas is a column of four buttons, each of which
brings up another window full of controls.  One thing to note: these
windows are "modeless," which means that you can still use any other
window while they are open.  If you have enough screen space, you may
find room to arrange them the most commonly used windows are all
accessable at the same time.

The "Change Output Mode..." button below the "Output" area brings up
another control window.

The next row of controls in the main window is for HAMLAB PLUS's
cropping and scaling features.

Cropping

Cropping cuts out a rectangular area of an image and is useful for
removing borders or working on pieces of a large image.

HAMLAB PLUS can crop an image twice: once as it reads the original
image from disk ("input cropping") and once as it saves or displays
an image ("output cropping").  There are advantages and disadvantages
to both: the earlier an image is cropped, the less memory and time
later operations will take.  On the other hand, the later an image is
cropped, the fewer steps have to be recalculated if the cropping is
changed.

In general, input cropping is useful for working on small sections of
very large images, which may be impractical to process as a whole
due to excessive memory requirements or long processing time.  Output
cropping is useful for adjusting the borders of an image.

Input and Output crop share the same keyboard shortcuts.  The I and O
keys will switch the other shortcut key meanings from one type of
cropping to the other. (The underlines on the screen show the current
shortcuts.)

Both cropping control areas allow you to define the cropping area by
entering the width and height of the cropped area, and/or entering the
upper left "UL" and lower right "LR" corners of the cropping area.
You can reset a cropping area to the full image size with the "Full
Size" button.

In addition, while displaying an image, you can define a new Output
Crop area by holding down the shift key and holding down the left
mouse button to drag a rectangle on the screen.  When you release the
mouse button, the screen will be closed and the new cropping area will
be entered into the gadgets.  If you then hit the Display button, it
will reselect a palette and display the cropped area.

Scaling

Between the two cropping controls is the scaling control area.
HAMLAB PLUS can scale in image independently in the X and Y
directions to anything from 10% to 1000% of its original size.

You can scale an image either by percentages or by the desired output
size.  The "%" buttons allow you to control this independently for X
and Y scaling.  The ">>" buttons cycle through a few commonly used
scaling values as follows:

        X:      50%, 100%

        Y:      50%, 100%, 200%

These scaling values are also coded to run faster than other values.

The "Constrained" setting causes one scaling factor to change when you
change the other.  For example, if you double the X scaling value, the
Y scaling value would double, too.

Messages

Extending across the width of the main window is a three line message
area where informational and error messages from different operations
will be displayed.  Older messages will scroll off the top.

Main Buttons

Finally, we get to the main functions of HAMLAB PLUS.  These six large
buttons at the bottom of the main window control the main functions.

OPEN

This function brings up a file requester, allowing you to select a
file.  HAMLAB PLUS will attempt to identify the file and, if
successful, load an input filter program, which will start processing
the file and return some basic information about the size and
(optionally) the depth of the image.

Occasionally, some additional buffering must be done by the input
filter.  This usually occurs when the image is stored in some kind of
order other than the top-to-bottom scanline order that HAMLAB PLUS
expects.  If buffering is needed, a progress window will indicate the
progress of the buffering and allow you to cancel it.

There are two kinds of HamLab filters:

        "new" filters for HamLab 2.x

        "old" filters for HamLab 1.x (will work with HamLab 2.x)

New filters have lower overhead than old filters and should generally
be faster.  They also provide HAMLAB PLUS with more information.  For
example, old filters cannot send messages to the HAMLAB PLUS window.

EXPORT

This function allows HAMLAB PLUS to export 24-bit data, after it has
been scaled and color-corrected, through a separate "exporter"
program, which can save it in some 24-bit format.

The export button brings up a scrolling list, from which you pick the
exporter you wish to use.  HAMLAB PLUS will run that exporter program,
which will usually display a file requester, allowing you to choose
the name of the file to be saved.  A progress window indicates the
progress of the export function and allows you to cancel it.

DISPLAY

This button starts the display operation.  Depending on your settings,
a great deal of calculations may be required to go from the original
image to something that can be displayed, so this function can take a
while.  As usual, a progress window is displayed, giving you a chance
to cancel the operation.

Once HAMLAB PLUS has done enough calculating to start displaying data,
it will bring a display screen to the front and start rendering into
it.  You don't have to wait for rendering to complete before you can
abort, pan, crop, or start saving the display.

HAMLAB PLUS uses two memory or disk "caches" to save intermediate
results from prior operations, to minimize unnecessary recalculation.
Cache controls are explained later.

Closing the Display

To close the display, click the right mouse button or press the
space bar in the display screen.

Panning the Display

To pan the display (i.e. scroll to a different area of the image),
either use the arrow keys or press and hold the left mouse button
and drag in the direction to pan.

Cropping the Display

To crop the display, press and hold the shift key. (The cursor will
turn into a cross-hair.)  Then position the mouse to one corner of
the desired cropped area, press and hold the left mouse button, and
drag out a rectangle to the other corner.  When you release the
mouse button, the display will close and the output cropping area
will be updated.

Saving from the Display

As long as the display screen is open, you can save its contents
very quickly because no additional rendering calculations are
required.   You may even start saving the picture before it has
completed displaying by pressing the 'S' key in the display window.
This will bring up the usual save file requester, then the save
operation will catch up to the display.  After that, each line will
be displayed and saved at the same time.

SAVE

This button starts the save operation. It first brings up a file
requester to allow you to specify the name of the file to be saved.

Like the display operation, the amount of processing required may vary
depending on how your caches are configured and how many settings
you've changed since the last operation.

REVERT

This button reverts all settings to those which were used the last
time you successfully displayed, saved, or exported an image.  It is
useful if you accidentally change a setting that would cause
everything to be recalculated.

CLEAR

This button releases all memory and/or temporary disk files associated
with the current image, and unloads the input filter program.

THE ABOUT WINDOW

This window displays some copyright and version information, plus it
also displays the amount of free memory (as two numbers: chip / fast),
the amount of storage in use (two numbers: memory (fast) and temporary
disk space), and the current AREXX port ID.

Note that the amount of storage in use is only what is in use by the
caches, if any.  This doesn't count anything like CHIP memory used for
a display, or any of the many short-lived buffers that HAMLAB PLUS
will use for its processing.

THE CONFIGURATION WINDOW

This window allows you to control some miscellaneous configuration
items.

Fix HAM Scrolling

Turning this setting on will make HAM images larger than the screen
more usable by fixing the glitches that develop down the left edge of
the image if you scroll the picture so that real left edge of the
image is not visible.  This option will slow down scrolling somewhat.

This option does not affect the way an image is saved, only how
it is displayed.

Beep after long functions

This setting will cause HAMLAB PLUS to beep and flash the screen
after a Display, Save, or Export function has completed.

Ask before abandon

Turning this setting on will suppress the "Abandon current image?"
requesters that would normally apper if you are about to discard
all your work on an image without saving it.

12-bit cache

This setting controls the maximum allowable size of 12-bit image data
that will be kept in memory or on disk.  Two numbers are entered here,
separated by a slash.  The first is the maximum size of a memory
cache.  The second is the maximum size of a temporary disk file.  Both
sizes are in bytes.  HAMLAB PLUS needs two bytes for every pixel of
in a 12-bit cache.

You may set either or both sizes to zero.  This won't require any
memory, but will mean that every pass will require more calculations
because HAMLAB PLUS must restart earlier in the process.

24-bit cache

This setting controls the maximum allowable size of the 24-bit image
data that will be kept in memory or on disk.  As above, the two
numbers control the maximum memory and disk size in bytes.  HAMLAB
PLUS needs 3 bytes for each pixel in a 24-bit cache.

For more information about how the caches are used, see THE HAMLAB
PLUS PIPELINE later in this document.

Note: Both caches will attempt to use a single large block of memory.
If you wish to keep your caches in memory, but don't have large
enough areas available, consider setting the temporary path to the
RAM disk and use "disk" caches instead.

Temporary path

This setting specifies the directory where temporary disk cache files
will be stored.

Filter path

This setting specifies the directory where filters and exporters are
located.

Pipe device

This setting specifies the name of the pipe device.  The pipe device
is only used when reading an image with a HamLab 1.x ("old") input
filter.

Normally this should be set to "PIPE:" but you may wish to use a
different named pipe device for improved performance.

AREXX console

This setting specifies the console window to be used for AREXX.  A
console window specification looks like:

        CON:left/top/width/height/title/flags

See "Using the Amiga System Software" (the AmigaDOS User's Manual)
for more information on how to specify a console window.

Load

Displays the file requester and allows you to select a new config file
for loading.  All commands in the config file will be applied, and
the associated settings will be changed.

Note that a config file can change any number of settings, so the
"Load" operation does not reset everything before loading a new
configuration.

Save

Saves some of the current values (generally those in the output
window) to a new config file.  See the command reference docs for
information on exactly which settings are saved.

In general, this command saves the settings that are likely to change
from image to image. It is appropriate for defining commonly used
groups of settings.

Save All

Saves all current values (except cropping, which is reset when a new
picture is opened) to a new config file.

This command saves everything including the more permanent
configuration settings, i.e. the ones that you rarely change.  It is
appropriate for updating your main config file.

Scan Filters

This function scans the directory specified by the "Filter Path"
setting for HamLab filters (new style only) and exporters.  For each
filter or exporter program it finds, the program will be automatically
queried and the information that it returns will be stored just as if
it had been read from a config file.

The procedure to add new filters and exporters is simple: drop the
filter into the filterpath directory, run HamLab Plus, click on
"Scan Filters," then click on "Save All" and replace the old config
file.


THE COLOR CONTROL WINDOW

HAMLAB PLUS can apply color correction to an image using "color
response curves."  These "curves" are really look-up tables that
apply separately to the 8-bit red, green, and blue values that make
up a 24-bit image.

By default, the color response curves map each input value to an
identical output value (0 -> 0, 1 -> 1, 2 -> 2, ...) so that they
have no effect.  Changing that mapping allows you to control things
like brightness and contrast independently for red, green, and blue.

The color control window allows you to manipulate the color response
curves.  You can draw the curves by hand, or use the controls in this
window to modify them

The three buttons above each curve control which curves are active.
Only active curves can be drawn into or affected by the controls.
Note that when you draw in one active area, all active curves are
affected.

Contrast

This controls the slope of the active curve(s).  A steeper slope
results in a more contrasty image. ('+' means "make steeper")

Brightness

This moves the active curve(s) up and down without changing slope.
Moving a curve up will increase the brightness of the image.

Gamma

This modifies the active curve(s) in a nonlinear fashion.  'C' stands
for Compensate, and 'U' for Uncompensate.  These buttons will modify
the curve by the factor to their right, which can be any number
between 0.1 and 9.9.  (You must enter a digit, period, digit here.)

Compensating with a gamma greater than one will tend to increase the
contrast of darker areas while decreasing the contrast of lighter
areas.  This can do wonders to bring out details lost in shadow
without destroying the brighter areas of an image.

Uncompensating with a gamma greater than one will have the opposite
effect: contrast in shadows will be diminished, while contrast in
highlights will be enhanced.

Negate

This turns all active curve(s) upside-down, resulting in output that
looks like a photographic negative.  A nice gee-whiz feature, but
probably not terribly useful.

Smooth

This button smooths out some of the bumps in the active curve(s).  You
can hold this button down and the curves will get progressively
smoother.

Init

This button resets all active curves to initial 45-degree line, so
that they basically have no effect on the image.

Load

This button allows the active curve(s) to be loaded from disk.  They
can be loaded from either a HamLab format text file, or from the CLUT
chunks of some 24-bit IFF files.

Save

This button saves ALL curves (not just the active ones) to a HamLab
format text file.

Monotonic

This button will fill in the holes in the active curve(s) so that the
curve is either always increasing or always decreasing.  In other
words, it prevents the same curve from going both up and down.

Step Size

This setting controls how "fast" the contrast and brightness controls
work.  The higher the number selected, the faster (but coarser) they work.

THE OUTPUT MODE WINDOW

This window controls all of the different output options of
HAMLAB PLUS.  One thing to note: the "Output" text area in the main
window displays a "shorthand" version of most of the information in
this window.

Some controls should be obvious: resolution, interlace, and bit planes
are all straightforward.  Illegal combinations like hi-res HAM are not
allowed.

Palette Mode

The palette mode controls whether this is a normal image (i.e. one
palette is chosen for the whole image), or whether the image is
"sliced," which means that the Amiga's custom chips are used to change
some of the color palette in mid-screen.  You have the option of
changing anywhere between 1 and 15 colors in each slice. (A slice is a
single line on a non-interlaced screen or two lines on an interlaced
screen.)

Slicing 15 colors is the old "SHAM" technique, which can have
problems, depending on how much your display is overscanned and
whether you are running in PAL.  Slicing 7 colors should work
properly in all display modes under all conditions on all machines.

  SEVEN COLORS IS THE MOST YOU CAN SLICE WHILE REMAINING COMPLETELY
  COMPATIBLE WITH ALL AMIGAS.

Additionally, you can "freeze" a palette once it has been selected, so
that it will be used for subsequent images, skipping the lengthy step
of picking a new palette.

You cannot freeze the palette of a sliced picture.

Finally, you can load and save a palette.  Loading a palette will also
freeze it.  Saving a palette is only possible when you're not using a
sliced mode.

Palettes are saved as IFF files that can be read by other programs,
Dpaint IV, for example.

Save Mode

This controls how a "sliced" image is saved as an IFF file.

PCHG will write a "multi-palette" file, a new standard, which was
developed by Sebastiano Vigna, the author of Mostra, a shareware
all-purpose IFF display program.  Mostra versions 1.07 and later can
display multi-palette files.

SHAM writes a "SHAM" (Sliced HAM) file.  Non-HAM files may be saved
with this mode, but I doubt if anything will handle them correctly.

"Dynamic" writes a "dynamic" file, with the information expected by a
program like Dyna-Show or DynaMate.  Again, any file may be saved with
this mode, but only HAM and 4 bitplane hi-res are likely to be
supported by other programs.

You can check more than one save mode at a time.  This will save the
same information up to three different ways in the same IFF file.
(Using three different IFF "chunks".)  This lets you save a single
picture with SHAM or dynamic information for older viewers and PCHG
for modern viewers.

Lock Background

This option forces HAMLAB PLUS to use the background color of the
original image as the background/border color of the output image.
If this is unchecked, then HAMLAB PLUS will pick a palette without
regard to the original background color, then use the closest match
to the original background as the output background/border color.

24->12 Dither

This selects the type of dithering used to reduce a 24-bit image to a
12-bit image.  The following choices are available:

None            No dithering
Floyd-Steinberg Serpentine error diffusion to 4 adjacent pixels
Jarvis          Serpentine error diffusion to 12 adjacent pixels
Stucki          Slightly different 12-pixel error diffusion
Ordered         Dispersed dot ordered dither
Random          Random dither
Spiral-Dot      Clustered dot ordered dither


12->Display Dither

This selects the type of dithering used to reduce a 12-bit image to
the small number of colors (2-64) actually used in the output.  This
has no effect on HAM images.  The following choices are available:

None            No dithering
Floyd-Steinberg Serpentine error diffusion to 4 adjacent pixels
Jarvis          Serpentine error diffusion to 12 adjacent pixels
Stucki          Slightly different 12-pixel error diffusion

Why two different dithering controls?  The reason has to do with the
two step process HAMLAB PLUS uses to go from 24-bit data to something
that the Amiga can display.  (More details on this are in the
following section.)  These two steps are:

1) Reduce the picture to the Amiga's 4096-color (12-bit) palette
2) Reduce the picture to the number of colors that the Amiga can
   actually display at one time.

Here's an example:  Let's say we start with a 24-bit image that
contains, among other things, 200 different intensities of pure blue.
For the first step, we must reduce the number of blues to 15, because
that's all we can represent with only 4 bits to control the blue.
For the second step, we may only be able to display 16 colors for the
entire image, and perhaps that leaves us with only 3 different blues
in our final palette, so the second step must reduce the number of
blues from 15 to 3.

In both steps, dithering helps prevent "banding," which can happen
when gradual color changes (like our original 200 blues) are
represented with only a few (in this case, 15 or 3) colors.

The two dithering steps can be controlled independently because
dithering takes time, and sometimes one or both steps are unnecessary.
For example, if you want to convert an Amiga HAM picture to hi-res,
then 24->12 dithering is not necessary because the picture already
has a 12-bit palette, but 12->display dithering may be very helpful
because we're going from 4096 possible colors to only 16.

One Step Dither

Finally, there is one more option which changes the way HAMLAB PLUS
dithers.  Selecting the "One Step Dithering" control does two things:

1.  It causes the 24->12 dither setting to be ignored
2.  It uses the 12->display dithering method, but goes from 24-bit
    data direct to the display in one step.

Dithering in one step is more accurate than doing it in two steps,
since some information is lost by keeping only a 12-bit intermediate
value for the two step process.  However, one-step dithering means
that the 24-bit data must be accessed more often, so it is probably
not practical to use unless you are using a 24-bit cache.

One-step dithering has no effect on HAM images.

THE AREXX CONSOLE

This window allows you to enter AREXX commands by name.  You can enter
a HamLab AREXX command, or the name of an AREXX macro.

HamLab AREXX macros are stored in the REXX: directory and end with
".hl"

Examples:

CMD> message "hello there"
(displays "hello there" in the message area)

CMD> foobar
(since there is no built-in foobar command, this attempts to run
REXX:foobar.hl)

See the command documentation for a complete list of AREXX commands
and their syntax.

AREXX FUNCTION KEYS

HamLab Plus also allows you to execute AREXX macros using function
keys when the main window is active.  The F1 key will execute
"F1.hl", F2 will execute "F2.hl", and so on.  The Control, Alt, and
Shift keys will modify the name of the command to be executed by
adding a 'c', 'a' or 's' to the beginning of the file name, so
Control-Alt-Shift-F10 will execute the macro named "casF10.hl"

THE HAMLAB PLUS PIPELINE AND CACHES

HAMLAB PLUS does all of its processing in a "pipeline" fashion,
which means that all operations happen in a particular order, with
the output of an earlier step serving as the input of the next step.
HAMLAB PLUS also does all operations in a fixed order.  While this
loses some flexibility, it does avoid one major limitation: memory.
HAMLAB PLUS can work on practically any size image, and, at a minimum,
only needs to keep about one or two scan lines of that image in memory
at one time.

This does mean that some things have to be done twice.  For normal
processing, HAMLAB PLUS must first process the entire image to choose
a palette, then make a second pass on the same image to convert it to
that palette.  This would mean that practically all of the steps in
HAMLAB PLUS's process, from reading the original image, through all
cropping, scaling, dithering, etc., would be done twice.

HAMLAB PLUS does allow a way to avoid a lot of repitition, if you have
either memory or disk space sufficient to hold an image.  It does this
by using two caches, which are temporary 12- and/or 24-bit images held
at certain points in the pipeline, and saved either in memory or on
disk.  Using a cache means that after HAMLAB PLUS has selected a
palette, it doesn't need to go all the way back to the original image
to be able to display it.  Instead, it need only go back to the
12-bit cache, which holds the image after much of the processing has
already been done.

If you use caches, they will stick around until you exit the program
or use the Clear function, or until you change a setting which means
that some processing upstream of the cache must be re-done.

Here is the order in which HAMLAB PLUS does its operations (top to
bottom).  Where the caches fall in this order is also shown.

        reading original image from disk

        input cropping

        [24-bit cache]

        scaling

        color correction

    Here is where an exporter fits in -- it takes 24-bit data after
    scaling and color correction, and saves it in a file.

        reducing to a 12-bit image (possibly with dithering)

        [12-bit cache]

        palette color selection

        rendering to display or output file (possibly with dithering)

From this pipeline, we can see that if we're using both 12-bit and
24-bit caches, then if we change the display mode (meaning we need to
choose a new palette) then we only need to go back as far as the
12-bit cache to calculate a new palette.  However, if we change the
size of the picture, then we have to go back to the 24-bit cache,
resize the picture, and build a new 12-bit cache.